<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Code Manipulation API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('API_BT.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Code Manipulation API </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Code Manipulation API exposes the full power of DynamoRIO, allowing tools to observe and modify the application's actual code stream as it executes. Modifications are not limited to trampoline insertion and can include arbitrary changes. We divide the API description into the following sections:</p>
<ul>
<li><a class="el" href="API_BT.html#sec_IR">Instruction Representation</a></li>
<li><a class="el" href="API_BT.html#sec_events_bt">Events</a></li>
<li><a class="el" href="API_BT.html#sec_decode">Decoding and Encoding</a></li>
<li><a class="el" href="API_BT.html#sec_64bit">64-bit Versus 32-bit Instructions</a></li>
<li><a class="el" href="API_BT.html#sec_IR_utils">Utilities</a></li>
<li><a class="el" href="API_BT.html#sec_translation">State Translation</a></li>
<li><a class="el" href="API_BT.html#sec_pcache">Persisting Code</a></li>
<li><a class="el" href="API_samples.html#bt_examples">Discussion of Selected Samples</a></li>
<li><a class="el" href="API_BT.html#sec_startstop">Running a Subset of an Application</a></li>
</ul>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_IR"></a>
Instruction Representation</h1>
<p>The primary data structures involved in instruction manipulation are the <code><a class="el" href="structinstr__t.html">instr_t</a></code>, which represents a single IA-32 instruction, and the <code>instrlist_t</code>, which is a linked list of instructions. The header files <a class="el" href="dr__ir__instrlist_8h.html" title="Functions to create and manipulate lists of instructions.">dr_ir_instrlist.h</a> and <a class="el" href="dr__ir__instr_8h.html" title="Functions to create and manipulate instructions.">dr_ir_instr.h</a> list a number of functions that operate on these data structures, including:</p>
<ul>
<li>Routines to create new instructions.</li>
<li>Routines to iterate over an instruction's operands.</li>
<li>Routines to iterate over an <code>instrlist_t</code>.</li>
<li>Routines to insert and remove an <code><a class="el" href="structinstr__t.html">instr_t</a></code> from an <code>instrlist_t</code>.</li>
</ul>
<p>As we will see in the the <a class="el" href="API_BT.html#sec_events_bt">Events</a> section that follows, a client usually interacts with <code>instrlist_t's</code> in the form of <em>basic</em> <em>blocks</em> or <em>traces</em>. A basic block is a sequence of instructions that terminates with a control transfer operation. Traces are frequently-executed sequences of basic blocks that DynamoRIO forms dynamically as the application executes, i.e., <em>hot</em> code. Collectively, we refer to basic blocks and traces as <em>fragments</em>. Both basic blocks and traces present a linear view of control flow. In other words, instruction sequences have a single entrance and one or more exits. This representation greatly simplifies analysis and is a primary contributor to DynamoRIO's efficiency.</p>
<p>The instruction representation includes all of the operands, whether implicit or explicit, and the condition code effects of each instruction. This allows for analysis of liveness of registers and condition codes.</p>
<p>DynamoRIO's IR is mostly opaque to clients. Key data structures have their sizes exposed to allow for stack allocation, but their fields are opaque. In order to examine them, clients must call IR accessor routines in DynamoRIO. While this makes DynamoRIO ABI compatible with prior releases, there is a performance cost to calling through to an exported routine every time the client touches an instruction. Clients that are not concerned with ABI compatibility can turn many of these export routine calls into inline functions or macros by setting the CMake variable <code>DynamoRIO_FAST_IR</code> on or defining <code>DR_FAST_IR</code> before including <a class="el" href="dr__api_8h.html" title="Top-level include file for DynamoRIO API.">dr_api.h</a>. This removes some of the error checking that DynamoRIO performs on calls from the client, so it should typically be enabled only in a release build. Furthermore, some of the macros evaluate their arguments twice, so clients should avoid passing arguments with side effects.</p>
<p>See <a class="el" href="API_BT.html#sec_decode">Decoding and Encoding</a> for further information on creating instructions from scratch, decoding, encoding, and disassembling instructions.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_events_bt"></a>
Events</h1>
<p>The core of a client's interaction with DynamoRIO occurs through <em> event hooks</em>: the client registers its own callback routine (or <em>hook</em>) for each event it is interested in. DynamoRIO calls the client's event hooks at appropriate times, giving the client access to key actions during execution of the application. The <a class="el" href="using.html#sec_events">Common Events</a> section describes events common to the entire DynamoRIO API. Here we discuss the events specific to the Code Manipulation portion.</p>
<p>DynamoRIO provides two events related to application code fragments: one for basic blocks and one for traces (see <a class="el" href="dr__events_8h.html#a043a3588c4cf0c2d6838140fce530e72">dr_register_bb_event()</a> and <a class="el" href="dr__events_8h.html#a88a19a6822654caf18c017e145f48a57">dr_register_trace_event()</a>). Through these fragment-creation hooks, the client has the ability to inspect and modify any piece of code that DynamoRIO emits before it executes. Using the basic block hook, a client sees <em>all</em> application code. The trace-creation hook provides a mechanism for clients to instrument only frequently-executed code paths.</p>
<h2><a class="anchor" id="sec_control_points"></a>
Transformation Versus Execution Time</h2>
<p>DynamoRIO's basic block and trace events are raised when the corresponding application code is being transferred to the software code cache for execution. <em>No event is raised on each execution of this code from the code cache</em>. In a typical run, a particular block of code will only be seen once in an event. It will subsequently execute many times in the code cache.</p>
<p>The point where the event is raised, where the application code is being copied into the cache, is called <em>transformation time</em>. This is where a client can insert instrumentation to monitor the code, or can modify the application code itself. The repeated executions within the code cache of this instrumented or modified code are referred to as <em>execution time</em>. It is important to understand the distinction.</p>
<p>The code manipulation API is highly efficient in that fragment creation comprises a small part of DynamoRIO's overhead. A client's instrumentation time actions rarely add substantial overhead for most target applications. Instead, it is extra actions taken by added instrumentation code acting at execution time that affects efficiency.</p>
<h2><a class="anchor" id="sec_events_bb"></a>
Basic Block Creation</h2>
<p>Through the basic block creation event, registered via <a class="el" href="dr__events_8h.html#a043a3588c4cf0c2d6838140fce530e72">dr_register_bb_event()</a>, the client has the ability to inspect and transform any piece of code prior to its execution. The client's hook receives three parameters:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209">dr_emit_flags_t</a> new_block(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *tag, instrlist_t *bb,</div>
<div class="line">                          <span class="keywordtype">bool</span> for_trace, <span class="keywordtype">bool</span> translating);</div>
</div><!-- fragment --><ul>
<li><code>drcontext</code> is a pointer to the input program's machine context. Clients should not inspect or modify the context; it is provided as an opaque pointer (i.e., <code>void *</code>) to be passed to API routines that require access to this internal data.</li>
</ul>
<ul>
<li><code>tag</code> is a unique identifier for the basic block fragment.</li>
</ul>
<ul>
<li><code>bb</code> is a pointer to the list of instructions that comprise the basic block. Clients can examine, manipulate, or completely replace the instructions in the list.</li>
</ul>
<ul>
<li><code>for_trace</code> indicates whether this callback is for a new basic block (false) or for adding a basic block to a trace being created (true). The client has the opportunity to either include the same modifications made to the standalone basic block, or to use different modifications, for the code in the trace.</li>
</ul>
<ul>
<li><code>translating</code> indicates whether this callback is for basic block creation (false) or is for address translation (true). This is further explained in <a class="el" href="API_BT.html#sec_translation">State Translation</a>.</li>
</ul>
<p>The return value of the basic block callback should generally be DR_EMIT_DEFAULT; however, time-varying instrumentation or complex code transformations may need to return DR_EMIT_STORE_TRANSLATIONS. See <a class="el" href="API_BT.html#sec_translation">State Translation</a> for further details. A tool that wants to persist its code to a file for fast re-use on subsequent runs can include the DR_EMIT_PERSISTABLE flag in its return value. See <a class="el" href="API_BT.html#sec_pcache">Persisting Code</a> for more information.</p>
<p>To iterate over instructions in an <code>instrlist_t</code>, use the <a class="el" href="dr__ir__instrlist_8h.html#ac9a47c1b7376ca06d8dcb4b3094e5a67">instrlist_first()</a>, <a class="el" href="dr__ir__instrlist_8h.html#ae2f37fe5e485b5aed7a196a5a1348d4a">instrlist_last()</a>, and <a class="el" href="dr__ir__instr_8h.html#a9a11b5b0700f7601087e2fda87175040">instr_get_next()</a> routines. For example:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209">dr_emit_flags_t</a> new_block(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *tag, instrlist_t *bb,</div>
<div class="line">                          <span class="keywordtype">bool</span> for_trace, <span class="keywordtype">bool</span> translating)</div>
<div class="line">{</div>
<div class="line">  <a class="code" href="structinstr__t.html">instr_t</a> *instr, *next;</div>
<div class="line">  <span class="keywordflow">for</span> (instr = <a class="code" href="dr__ir__instrlist_8h.html#ac9a47c1b7376ca06d8dcb4b3094e5a67">instrlist_first</a>(bb);</div>
<div class="line">       instr != <a class="code" href="dr__ir__instrlist_8h.html#ae2f37fe5e485b5aed7a196a5a1348d4a">instrlist_last</a>(bb);</div>
<div class="line">       instr = next) {</div>
<div class="line">    next = <a class="code" href="dr__ir__instr_8h.html#a9a11b5b0700f7601087e2fda87175040">instr_get_next</a>(instr);</div>
<div class="line">    <span class="comment">/* do some processing on instr */</span></div>
<div class="line">  }</div>
<div class="line">  <span class="keywordflow">return</span> <a class="code" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a7d25c4546544d1a8c0b77c69230772eb">DR_EMIT_DEFAULT</a>;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="sec_Meta"></a>
Application Versus Meta Instructions</h2>
<p>Changes to the instruction stream made by a client fall into two categories: changes or additions that should be considered part of the application's behavior, versus additions that are observational in nature and are not acting on the application's behalf. The latter are called <em>meta</em> instructions.</p>
<p>Meta instructions are marked using these API routines:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__ir__instr_8h.html#ad0919782b67d3918ec6feb838e373f15">instr_set_meta</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#a3b0b7e9e09a9a85ca1a707da3ded6f69">instrlist_meta_preinsert</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#a98218650e1f61b58c5478cf68e25d9da">instrlist_meta_postinsert</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#a824eaa9075a7aaf443b4cc4180eec81e">instrlist_meta_append</a>()</div>
</div><!-- fragment --><p>DynamoRIO performs some processing on the basic block after the client has finished with it, primarily modifying branches to ensure that DynamoRIO retains control after execution. It is important that the client mark any control-flow instructions that it does not want treated as application instructions as <em>meta</em> instructions. Doing so informs DynamoRIO that these instructions should execute natively rather than being trapped and redirected to new basic block fragments.</p>
<p>Through meta instructions, a client can add its own internal control flow or make a call to a native routine. The target of a meta call will not be brought into the code cache by DynamoRIO. However, such native calls need to be careful to remain transparent (see <a class="el" href="API_BT.html#sec_clean_call">Clean Calls</a>).</p>
<p>Meta instructions are normally observational, in which case they should not fault and should have a NULL translation field. It is possible to use meta instructions that deliberately fault, or that could fault by accessing application memory addresses, but only if the client handles all such faults. See <a class="el" href="API_BT.html#sec_translation">State Translation</a> for more information on fault handling.</p>
<p>Meta instructions are visible to client code, if using <a class="el" href="dr__ir__instr_8h.html#a9a11b5b0700f7601087e2fda87175040">instr_get_next()</a> and <a class="el" href="dr__ir__instrlist_8h.html#ac9a47c1b7376ca06d8dcb4b3094e5a67">instrlist_first()</a>. To traverse only application (non-meta) instructions, a client can use the following API functions instead:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__ir__instr_8h.html#a1114903afc8f9a3539aed43330117627">instr_get_next_app</a>()</div>
<div class="line"><a class="code" href="dr__ir__instrlist_8h.html#a7facdfdbc94dff0029e1c7a0be55a934">instrlist_first_app</a>()</div>
</div><!-- fragment --><p>We recommend that clients follow a disciplined model that separates application code analysis versus insertion of instrumentation. The <a class="el" href="page_drmgr.html">Multi-Instrumentation Manager</a> Extension facilitates this by separating application transformation, application analysis, and instrumentation. However, even with this separation, label instructions and in some cases other meta instructions (e.g., from <a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native()</a>) are added during application transformation which should be skipped during analysis. Using <a class="el" href="dr__ir__instrlist_8h.html#a7facdfdbc94dff0029e1c7a0be55a934">instrlist_first_app()</a> and <a class="el" href="dr__ir__instr_8h.html#a1114903afc8f9a3539aed43330117627">instr_get_next_app()</a> is recommended during application analysis: it automatically skips non-application (meta) instructions, which at that stage are guaranteed to be either labels or to have no effect on register state or other key aspects of application code analysis.</p>
<p>While DynamoRIO attempts to support arbitrary code transformations, its internal operation requires that we impose the following limitations:</p>
<ul>
<li>If there is more than one application branch, only the last can be conditional.</li>
<li>An application conditional branch must be the final instruction in the block.</li>
<li>There can only be one indirect branch (call, jump, or return) in a basic block, and it must be the final application branch in the block.</li>
<li>The exit control-flow of a block ending in a system call cannot be changed.</li>
</ul>
<p>Application instructions, or non-meta instructions, in addition to being processed (and followed if control flow), are also considered safe points for relocation for the rare times when DynamoRIO must move threads around. Thus a client should ensure that it is safe to re-start an application instruction at the translation field address provided.</p>
<h2><a class="anchor" id="sec_events_trace"></a>
Trace Creation</h2>
<p>DynamoRIO provides access to traces primarily through the trace-creation event, registered via <a class="el" href="dr__events_8h.html#a88a19a6822654caf18c017e145f48a57">dr_register_trace_event()</a>. It is important to note that clients are not required to employ the trace-creation event to ensure full instrumentation. Rather, it is sufficient to perform all code modification using the basic block event. Any basic blocks that DynamoRIO chooses to place in a trace will contain all client modifications (unless the client behaves differently in the basic block hook when its <code>for_trace</code> parameter is true). The trace-creation event provides a mechanism for clients to instrument <em>hot</em> code separately.</p>
<p>The parameters to the trace-creation event hook are nearly identical to those of the basic block hook:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209">dr_emit_flags_t</a> new_trace(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *tag, instrlist_t *trace,</div>
<div class="line">                          <span class="keywordtype">bool</span> translating);</div>
</div><!-- fragment --><ul>
<li><code>drcontext</code> is a pointer to the input program's machine context. Clients should not inspect or modify the context; it is provided as an opaque pointer (i.e., <code>void *</code>) to be passed to API routines that require access to this internal data.</li>
</ul>
<ul>
<li><code>tag</code> is a unique identifier for the trace fragment.</li>
</ul>
<ul>
<li><code>bb</code> is a pointer to the list of instructions that comprise the trace. Clients can examine, manipulate, or completely replace the instructions in the list.</li>
</ul>
<ul>
<li><code>translating</code> indicates whether this callback is for trace creation (false) or is for address translation (true). This is further explained in <a class="el" href="API_BT.html#sec_translation">State Translation</a>.</li>
</ul>
<p>The return value of the trace callback should generally be DR_EMIT_DEFAULT; however, time-varying instrumentation or complex code transformations may need to return DR_EMIT_STORE_TRANSLATIONS. See <a class="el" href="API_BT.html#sec_translation">State Translation</a> for further details.</p>
<p>DynamoRIO calls the client-supplied event hook each time a trace is created, just before the trace is emitted into the code cache. Additionally, as each constituent basic block is added to the trace, DynamoRIO calls the basic block creation hook with the <code>for_trace</code> parameter set to true. In order to preserve basic block instrumentation inside of traces, a client need only act identically with respect to the <code>for_trace</code> parameter; it can ignore the trace event if its goal is to place instrumentation on all code.</p>
<p>The constituent basic blocks will be stitched together prior to insertion in the code cache: conditional branches will be realigned so that their fall-through target remains on the trace, and inlined indirect branches will be preceded by a comparison against the on-trace target.</p>
<p>If the basic block callback behaves differently based on the <code>for_trace</code> parameter, different instrumentation will exist in the trace as opposed to the standalone basic block. If the basic block corresponds to the application code at the start of the trace (i.e., it is a trace head), the trace will shadow the basic block and the trace will be executed preferentially. If <a class="el" href="dr__tools_8h.html#a7600cc31d68dc0e30ab91261d08836ed">dr_delete_fragment()</a> is called, it will also delete the trace first and may leave the basic block in place. The flush routines (<a class="el" href="dr__tools_8h.html#abe87d17869a51a66d59eecf459d71cc0">dr_flush_region()</a>, <a class="el" href="dr__tools_8h.html#afa5ea6649e644074ca55f456c89264e8">dr_delay_flush_region()</a>, <a class="el" href="dr__tools_8h.html#a56909cf76e4a71fca13731053ef48928">dr_unlink_flush_region()</a>), however, will delete traces and basic blocks alike.</p>
<h2><a class="anchor" id="sec_events_translation"></a>
State Restoration</h2>
<p>If a client is only adding instrumentation (meta instructions) that do not reference application memory, and is not reordering or removing application instructions, then it need not register for this event. If, however, a client is modifying application code or adding instructions that could fault, the client must be capable of restoring the original context. DynamoRIO calls a state restoration event, registered via <a class="el" href="dr__events_8h.html#ae7a179ac7a2d01157e1ab2852f50c902">dr_register_restore_state_event()</a> or <a class="el" href="dr__events_8h.html#a000e59a3f500a2d4a1d0123ce6032f77">dr_register_restore_state_ex_event()</a>, whenever it needs to translate a code cache context to an original application context:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> restore_state(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *tag, <a class="code" href="struct__dr__mcontext__t.html">dr_mcontext_t</a> *mcontext,</div>
<div class="line">                   <span class="keywordtype">bool</span> restore_memory, <span class="keywordtype">bool</span> app_code_consistent)</div>
<div class="line"><span class="keywordtype">void</span> restore_state_ex(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">bool</span> restore_memory,</div>
<div class="line">                      <a class="code" href="struct__dr__restore__state__info__t.html">dr_restore_state_info_t</a> *info)</div>
</div><!-- fragment --><p>See <a class="el" href="API_BT.html#sec_translation">State Translation</a> for further details.</p>
<h2><a class="anchor" id="sec_events_del"></a>
Basic Block and Trace Deletion</h2>
<p>DynamoRIO can also provide notification of fragment deletion via <a class="el" href="dr__events_8h.html#a698501b03d64f07e1a32fc82c021b27a">dr_register_delete_event()</a>. The signature for this event callback is:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> fragment_deleted(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *tag);</div>
</div><!-- fragment --><p>DynamoRIO calls this event hook each time it deletes a fragment from the code cache. Such information may be needed if the client maintains its own data structures about emitted fragment code that must be consistent across fragment deletions.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_decode"></a>
Decoding and Encoding</h1>
<p>As discussed in <a class="el" href="API_BT.html#sec_events_bb">Basic Block Creation</a> and <a class="el" href="API_BT.html#sec_events_trace">Trace Creation</a>, a client's primary interface to code inspection and manipulation is via the basic block and trace hooks. However, DynamoRIO also exports a rich set of functions and data structures to decode and encode instructions directly. The following subsections overview this functionality.</p>
<h2><a class="anchor" id="sec_Decoding"></a>
Decoding</h2>
<p>DynamoRIO provides several routines for decoding and disassembling IA-32 instructions. The most common method for decoding is the <a class="el" href="dr__ir__utils_8h.html#a6f62065c2b7e764fe9fb0f46557e2264">decode()</a> routine, which populates an <code><a class="el" href="structinstr__t.html">instr_t</a></code> data structure with all information about the instruction (e.g., opcode and operand information).</p>
<p>When decoding instructions, clients must explicitly manage the <code><a class="el" href="structinstr__t.html">instr_t</a></code> data structure. For example, the following code shows how to use the <a class="el" href="dr__ir__instr_8h.html#a77b55daa2b3780d2c07e33b8330b2f62">instr_init()</a>, <a class="el" href="dr__ir__instr_8h.html#accd2bdee07d2e6ca0be3b252bc7b913f">instr_reset()</a>, and <a class="el" href="dr__ir__instr_8h.html#ae0f3cc7fb91265cb6c8eb15a84184c1f">instr_free()</a> routines to decode a sequence of arbritrary instructions:</p>
<div class="fragment"><div class="line"><a class="code" href="structinstr__t.html">instr_t</a> instr;</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#a77b55daa2b3780d2c07e33b8330b2f62">instr_init</a>(&amp;instr);</div>
<div class="line"><span class="keywordflow">do</span> {</div>
<div class="line">  <a class="code" href="dr__ir__instr_8h.html#accd2bdee07d2e6ca0be3b252bc7b913f">instr_reset</a>(dcontext, &amp;instr);</div>
<div class="line">  pc = <a class="code" href="dr__ir__utils_8h.html#a6f62065c2b7e764fe9fb0f46557e2264">decode</a>(dcontext, pc, &amp;instr);</div>
<div class="line">  <span class="comment">/* check for invalid instr */</span></div>
<div class="line">  <span class="keywordflow">if</span> (pc == NULL)</div>
<div class="line">    <span class="keywordflow">break</span>;</div>
<div class="line">  <span class="keywordflow">if</span> (<a class="code" href="dr__ir__instr_8h.html#ae1aac8cef8bb6ab075238e38ad6888a9">instr_writes_memory</a>(&amp;instr)) {</div>
<div class="line">    <span class="comment">/* do some processing */</span></div>
<div class="line">  }</div>
<div class="line">} <span class="keywordflow">while</span> (pc &lt; stop_pc);</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#ae0f3cc7fb91265cb6c8eb15a84184c1f">instr_free</a>(dcontext, &amp;instr);</div>
</div><!-- fragment --><p>The 64-bit build of DynamoRIO is capable of decoding 32-bit code as well. See <a class="el" href="API_BT.html#sec_64bit">64-bit Versus 32-bit Instructions</a> for full details.</p>
<h2><a class="anchor" id="sec_InstrGen"></a>
Instruction Generation</h2>
<p>Clients can construct instructions from scratch in two different ways:</p>
<ol type="1">
<li>Using the INSTR_CREATE_opcode macros that fill in implicit operands automatically: <div class="fragment"><div class="line"><a class="code" href="structinstr__t.html">instr_t</a> *instr = <a class="code" href="dr__ir__macros_8h.html#a648549a9f8c47a283ae9ffbd3a51fde8">INSTR_CREATE_dec</a>(dcontext, <a class="code" href="dr__ir__opnd_8h.html#a0714576ebc35cf7efe2855126ad716e1">opnd_create_reg</a>(REG_EDX));</div>
</div><!-- fragment --></li>
<li>Specifying the opcode and all operands (including implicit operands): <div class="fragment"><div class="line"><a class="code" href="structinstr__t.html">instr_t</a> *instr = <a class="code" href="dr__ir__instr_8h.html#a65f53f3c43c91833faf11b5e6cd9e905">instr_create</a>(dcontext);</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#a5e1efc53088af35fa0ed6eefd80af5dd">instr_set_opcode</a>(instr, <a class="code" href="dr__ir__opcodes_8h.html#aae05225933a42f81e7c4a9fb286596f9ac291f7f1164c416847b0b47b0a922ed9">OP_dec</a>);</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#aee0d80a8e69e8f0abe867f1903a107ea">instr_set_num_opnds</a>(dcontext, instr, 1, 1);</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#a8e843e39613655f6a5c49e081fe593c2">instr_set_dst</a>(instr, 0, <a class="code" href="dr__ir__opnd_8h.html#a0714576ebc35cf7efe2855126ad716e1">opnd_create_reg</a>(REG_EDX));</div>
<div class="line"><a class="code" href="dr__ir__instr_8h.html#a96bfa15e2f3a95174e36c80c585a24e3">instr_set_src</a>(instr, 0, <a class="code" href="dr__ir__opnd_8h.html#a0714576ebc35cf7efe2855126ad716e1">opnd_create_reg</a>(REG_EDX));</div>
</div><!-- fragment --></li>
</ol>
<p>When using the second method, the exact order of operands and their sizes must match the templates that DynamoRIO uses. The INSTR_CREATE_ macros in <a class="el" href="dr__ir__macros_8h.html" title="Instruction creation convenience macros.">dr_ir_macros.h</a> should be consulted to determine the order.</p>
<h2><a class="anchor" id="sec_Encoding"></a>
Encoding</h2>
<p>DynamoRIO's encoding routines take an instruction or list of instructions and encode them into the corresponding IA-32 bit pattern:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__ir__instr_8h.html#a1cd4d0740eb0a0bcd2d387685719263c">instr_encode</a>(), <a class="code" href="dr__ir__instrlist_8h.html#aaac5ae2bc9af179b56bbbe5efc14e8b5">instrlist_encode</a>() </div>
</div><!-- fragment --><p>When encoding a control transfer instruction that targets another instruction, two encoding passes are performed: one to find the offset of the target instruction, and the other to link the control transfer to the proper target offset.</p>
<p>The 64-bit build of DynamoRIO is capable of encoding 32-bit code as well. See <a class="el" href="API_BT.html#sec_64bit">64-bit Versus 32-bit Instructions</a> for details.</p>
<h2><a class="anchor" id="sec_disasm"></a>
Disassembly</h2>
<p>DynamoRIO provides several routines for printing instructions to a file or a buffer. These include <a class="el" href="dr__ir__utils_8h.html#a526fc9f23e78b5f1321891dc8f81b1b7">disassemble()</a>, <a class="el" href="dr__ir__opnd_8h.html#a7f2ed9f0c7db11d7a186f95505f1703a">opnd_disassemble()</a>, <a class="el" href="dr__ir__instr_8h.html#a6baf5239817b639791916f3cbd6c7b9d">instr_disassemble()</a>, <a class="el" href="dr__ir__instrlist_8h.html#ae8313ff5985340de519dfe4cc7555c60">instrlist_disassemble()</a>, <a class="el" href="dr__ir__utils_8h.html#a2c491ac5c40069f120b0ef512ccc7166">disassemble_with_info()</a>, <a class="el" href="dr__ir__utils_8h.html#a2e6a5d44647c481f50ee5208281617ba">disassemble_from_copy()</a>, and <a class="el" href="dr__ir__utils_8h.html#a3978e8cb7ba406cf7c9fed00b9c4a9bf">disassemble_to_buffer()</a>.</p>
<p>The style of disassembly can be controlled through the <a class="el" href="using.html#op_syntax_intel">-syntax_intel</a> (for Intel-style disassembly) and <a class="el" href="using.html#op_syntax_att">-syntax_att</a> (for AT&amp;T-style disassembly) runtime options, or the <a class="el" href="dr__ir__utils_8h.html#a3082c5db55039c72ae30e3276f622aae">disassemble_set_syntax()</a> function. The default disassembly style is DynamoRIO's custom style, which lists all operands (both implicit and explicit). The sources are listed first, followed by "-&gt;", and then the destinations.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_64bit"></a>
64-bit Versus 32-bit Instructions</h1>
<p>The 64-bit build of DynamoRIO uses 64-bit decoding and encoding by default, while the 32-bit build uses 32-bit. The 64-bit build is also capable of decoding and encoding 32-bit instructions. Each thread has a current mode that is used to determine how to interpret instructions while decoding, whose default matches the DynamoRIO build. The <a class="el" href="dr__ir__utils_8h.html#adf9a4f63eafc7f9725f7d5bf1725ab5c">set_x86_mode()</a> routine changes the current mode, while <a class="el" href="dr__ir__utils_8h.html#aa18c8ca0720c97403a0fa9371ae792e5">get_x86_mode()</a> queries the current mode.</p>
<p>Each instruction contains a flag indicating whether it should be encoded in 32-bit or 64-bit mode. When an instruction is created or decoded, the instruction's flag is set to the thread's current mode. It can be queried with <a class="el" href="dr__ir__instr_8h.html#acf3a5a5abd40c0c0694f037fcfac5705">instr_get_x86_mode()</a> and changed with <a class="el" href="dr__ir__instr_8h.html#a74814111812ff20b281f7350fb626746">instr_set_x86_mode()</a>.</p>
<p>For a 64-bit build of DynamoRIO, the instruction creation macros all use 64-bit-sized registers. The recommended model when generating 32-bit code is to use the macros to create an instruction list and before encoding to call <a class="el" href="dr__ir__instr_8h.html#a74814111812ff20b281f7350fb626746">instr_set_x86_mode()</a> and <a class="el" href="dr__ir__instr_8h.html#ae0db1cec99a6fff7dde7201a87ca8892">instr_shrink_to_32_bits()</a> on each instruction. Naturally any instruction that differs in more than register selection must be special-cased.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_IR_utils"></a>
Utilities</h1>
<p>In addition to instruction decoding and encoding, the API includes several higher-level routines to facilitate code instrumentation. These include the following:</p>
<ul>
<li>Routines to insert clean calls to client-defined functions.</li>
<li>Routines to instrument control-flow instructions.</li>
<li>Routines to spill registers to DynamoRIO's thread-private spill slots.</li>
<li>Routines to quickly save and restore arithmetic flags, floating-point state, and MMX/SSE registers.</li>
</ul>
<p>The following subsections describe these routines in more detail.</p>
<h2><a class="anchor" id="sec_clean_call"></a>
Clean Calls</h2>
<p>To make it easy to insert code into the application instruction stream, DynamoRIO provides a <em>clean call</em> mechanism, which allows insertion of a transparent call to a client routine. The <a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a> routine takes care of switching to a clean stack, setting up arguments to a call and making the call, optionally preserving floating point state, and preserving application state across the entire sequence.</p>
<p>Here is an example of inserting a clean call to the <code>at_mbr</code> function:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="dr__ir__instr_8h.html#a963ac2677038071fc295b3b6eb45ce1d">instr_is_mbr</a>(instr)) {</div>
<div class="line">  app_pc address = <a class="code" href="dr__ir__instr_8h.html#a57dbc129ab88dfdcf49f1105eba394a7">instr_get_app_pc</a>(instr);</div>
<div class="line">  uint opcode = <a class="code" href="dr__ir__instr_8h.html#a90d36984352b073089da3c91b901c853">instr_get_opcode</a>(instr);</div>
<div class="line">  <a class="code" href="structinstr__t.html">instr_t</a> *nxt = <a class="code" href="dr__ir__instr_8h.html#a9a11b5b0700f7601087e2fda87175040">instr_get_next</a>(instr);</div>
<div class="line">  <a class="code" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call</a>(drcontext, ilist, nxt, (<span class="keywordtype">void</span> *) at_mbr,</div>
<div class="line">                       <span class="keyword">false</span><span class="comment">/*don&#39;t need to save fp state*/</span>,</div>
<div class="line">                       2 <span class="comment">/* 2 parameters */</span>,</div>
<div class="line">                       <span class="comment">/* opcode is 1st parameter */</span></div>
<div class="line">                       <a class="code" href="dr__ir__macros_8h.html#aa32fcd12a03eb97ef42ded7b68a85203">OPND_CREATE_INT32</a>(opcode),</div>
<div class="line">                       <span class="comment">/* address is 2nd parameter */</span></div>
<div class="line">                       <a class="code" href="dr__ir__macros_8h.html#a74d7ad05e5371236dfd5b91b0767b690">OPND_CREATE_INTPTR</a>(address));</div>
<div class="line">}</div>
</div><!-- fragment --><p>Through this mechanism, clients can write analysis code in C or other high-level languages and easily insert calls to these routines in the instruction stream. Note, however, that saving and restoring machine state is an expensive operation. Performance-critical operations should be inlined for maximum efficiency.</p>
<p>The stack that DynamoRIO switches to for clean calls is relatively small: only 20KB by default. Clients can increase the size of the stack with the <a class="el" href="using.html#op_stack_size">-stack_size</a> runtime option. Clients should also avoid keeping persistent state on the clean call stack, as it is wiped clean at the start of each clean call.</p>
<p>The saved interrupted application state can be accessed using <a class="el" href="dr__ir__utils_8h.html#a91ffde2808c16e07f323c34affa72209">dr_get_mcontext()</a> and modified using <a class="el" href="dr__ir__utils_8h.html#a56568d24667f5d64264d0bad398727b3">dr_set_mcontext()</a>.</p>
<p>For performance reasons, clean calls do not save or restore floating point, MMX, or SSE state by default. If the clean callee is using floating point or multimedia operations, it should request that the clean call mechanism preserve the floating point state through the appropriate parameter to <a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a>. See also <a class="el" href="transparency.html#sec_trans_floating_point">Floating Point State, MMX, and SSE Transparency</a>.</p>
<p>If more detailed control over the call sequence is desired, it can be broken down into its constituent pieces:</p>
<ul>
<li><a class="el" href="dr__ir__utils_8h.html#a4608ec2db2a288aa5e2a53bb6d19054d">dr_prepare_for_call()</a></li>
<li>Optionally, <a class="el" href="dr__proc_8h.html#aac57f229cefee3abdc6a45dfa37557f6">dr_insert_save_fpstate()</a></li>
<li><a class="el" href="dr__ir__utils_8h.html#af2a3575059c29dae25ab02c9eb1d0ce9">dr_insert_call()</a></li>
<li>Optionally, <a class="el" href="dr__proc_8h.html#ae2f93e0bd2ccdd9e1fe15752198e6c57">dr_insert_restore_fpstate()</a></li>
<li><a class="el" href="dr__ir__utils_8h.html#a466c814771a85f9b53e6681f4dc5c957">dr_cleanup_after_call()</a></li>
</ul>
<p>DynamoRIO analyzes the callee target of each clean call and attempts to reduce the context switch size and, if the callee is simple enough, to automatically inline it. This analysis and potential inlining works best when the callee is fully optimized. Thus, we recommend using high optimization levels in clients, even when running DynamoRIO itself in debug build in order to examine whether callees are being inlined. See <a class="el" href="using.html#op_cleancall">-opt_cleancall</a> for information on how to adjust the aggressiveness of these optimizations and for a list of specific conditions that affect inlining.</p>
<h2><a class="anchor" id="sec_state"></a>
State Preservation</h2>
<p>To facilitate code transformations, DynamoRIO makes available its register spill slots and other state preservation functionality. It exports API routines for saving and restoring registers to and from thread-local spill slots:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__ir__utils_8h.html#af294ac021c84f5ec47230ee7df0e6c02">dr_save_reg</a>(), <a class="code" href="dr__ir__utils_8h.html#a453bc3ecddb4298ffdc1c429f30881b8">dr_restore_reg</a>(), and <a class="code" href="dr__ir__utils_8h.html#a5eab608c134db044f2d9453a8407d470">dr_reg_spill_slot_opnd</a>() </div>
</div><!-- fragment --><p>The values stored in these spill slots remain valid until the next application (i.e. non-meta) instruction and as such can be accessed from clean calls using:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__ir__utils_8h.html#abb63ecfaa5256688bab9a2921fc19227">dr_read_saved_reg</a>(), <a class="code" href="dr__ir__utils_8h.html#abf8d50d718883a1caf6a2de0fb3dbce3">dr_write_saved_reg</a>() </div>
</div><!-- fragment --><p>For longer term persistence DynamoRIO also provides a generic dedicated thread-local storage field for use by clients, making it easy to write thread-aware clients. From C code, use:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__tools_8h.html#a787aff5df1ded3de8a7ce9f3efef0594">dr_get_tls_field</a>(), <a class="code" href="dr__tools_8h.html#a05b499c8a3115e9ceb4c45dbee660738">dr_set_tls_field</a>() </div>
</div><!-- fragment --><p>To access this thread-local field from the code cache, use the following routines to generate the necessary code:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__ir__utils_8h.html#a3831354cc7402d68719d8055fb3e9931">dr_insert_read_tls_field</a>(), <a class="code" href="dr__ir__utils_8h.html#a982089284bd51339f448ec4b3928d3b4">dr_insert_write_tls_field</a>() </div>
</div><!-- fragment --><p>Since saving and restoring the <code>eflags</code> register is required for almost all code transformations, and since it is difficult to do so efficiently, we export routines that use our efficient method of arithmetic flag preservation:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__ir__utils_8h.html#a44636ca6809a9fb22cf817701de9ee09">dr_save_arith_flags</a>(), <a class="code" href="dr__ir__utils_8h.html#a563b0de37a51cb2e84337deef30a57cf">dr_restore_arith_flags</a>() </div>
</div><!-- fragment --><p>As just discussed in <a class="el" href="API_BT.html#sec_clean_call">Clean Calls</a>, we also export convenience routines for making <em>clean</em> (i.e., transparent) native calls from the code cache, as well as floating point and multimedia state preservation.</p>
<h2><a class="anchor" id="sec_branch_instru"></a>
Branch Instrumentation</h2>
<p>DynamoRIO provides explicit support for instrumenting call instructions, direct (or unconditional) branches, indirect (or multi-way) branches, and conditional branches. These convenience routines insert clean calls to client-provided methods, passing as arguments the instruction pc and target pc of each control transfer, along with taken or not taken information for conditional branches:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__ir__utils_8h.html#a359744bc2776333fbf8f057931ca8eeb">dr_insert_call_instrumentation</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#a3647b439211a8cd70c40478a4113e128">dr_insert_ubr_instrumentation</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#a919e2106df67eaaa5bc6c49d736543b5">dr_insert_mbr_instrumentation</a>()</div>
<div class="line"><a class="code" href="dr__ir__utils_8h.html#abe09a1a1ca19b343279a65141c20f0a1">dr_insert_cbr_instrumentation</a>()</div>
</div><!-- fragment --><h2><a class="anchor" id="sec_adaptive"></a>
Dynamic Instrumentation</h2>
<p>DynamoRIO allows a client to dynamically adjust its instrumentation by providing routines to flush all cached fragments corresponding to an application code region:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__tools_8h.html#abe87d17869a51a66d59eecf459d71cc0">dr_flush_region</a>()</div>
<div class="line"><a class="code" href="dr__tools_8h.html#a56909cf76e4a71fca13731053ef48928">dr_unlink_flush_region</a>()</div>
<div class="line"><a class="code" href="dr__tools_8h.html#afa5ea6649e644074ca55f456c89264e8">dr_delay_flush_region</a>()</div>
</div><!-- fragment --><p>In order to directly modify the instrumentation on a particular fragment (as opposed to replacing instrumentation on all copies of fragments corresponding to particular application code), DynamoRIO also supports directly replacing an existing fragment with a new <code>instrlist_t:</code> </p>
<div class="fragment"><div class="line"><a class="code" href="dr__tools_8h.html#a5421c0abd69da94ed3e7fb898d5bb132">dr_replace_fragment</a>()</div>
</div><!-- fragment --><p>However, this routine is only supported when running with the <a class="el" href="using.html#op_thread_priv">-thread_private</a> runtime option, and it replaces the fragment for the current thread only. A client can call this routine even while inside the to-be-replaced fragment (e.g., in a clean call from inside the fragment). In this scenario, the old fragment is executed to completion and the new code is inserted before the next execution.</p>
<p>For example usage, see the client sample <a class="el" href="API_samples.html#sec_ex3">Modifying Existing Instrumentation</a>.</p>
<h2><a class="anchor" id="sec_custom_traces"></a>
Custom Traces</h2>
<p>DynamoRIO combines frequently executed sequences of basic blocks into <em>traces</em>. It uses a simple profiling scheme based on <em>trace heads</em>, which are the targets of backward branches or exits from existing traces. Execution counters are kept for each trace head. Once a head crosses a threshold, the next sequence of basic blocks that are executed becomes a new trace.</p>
<p>DynamoRIO allows a client to build custom traces by marking its own trace heads (<em>in addition</em> to DynamoRIO's normal trace heads) and deciding when to end traces. If a client registers for the following event, DynamoRIO will call its hook before extending a trace (with tag <code>trace_tag</code>) with a new basic block (with tag <code>next_tag</code>):</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> query_end_trace(<span class="keywordtype">void</span> *drcontext, <span class="keywordtype">void</span> *trace_tag, <span class="keywordtype">void</span> *next_tag);</div>
</div><!-- fragment --><p>The client hook returns one of these values:</p>
<ul>
<li>CUSTOM_TRACE_DR_DECIDES = use standard termination criteria</li>
<li>CUSTOM_TRACE_END_NOW = end trace now</li>
<li>CUSTOM_TRACE_CONTINUE = do not end trace</li>
</ul>
<p>If using standard termination criteria, DynamoRIO ends the trace if it reaches a trace head or another trace (or certain corner-case basic blocks that cannot be part of a trace).</p>
<p>The client can also mark any basic block as a trace head with </p>
<div class="fragment"><div class="line"> <a class="code" href="dr__tools_8h.html#a9e262e93823dbc5914eca34540afbc07">dr_mark_trace_head</a>() </div>
</div><!-- fragment --><p>For example usage, see the callee-inlining client sample <a class="el" href="API_samples.html#sec_ex5">Custom Tracing</a>.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_translation"></a>
State Translation</h1>
<p>To support transparent fault handling, DynamoRIO must translate a fault in the code cache into a fault at the corresponding application address. DynamoRIO must also be able to translate when a suspended thread is examined by the application or by DynamoRIO itself for internal synchronization purposes.</p>
<p>If a client is only adding observational instrumentation (i.e., <a class="el" href="API_BT.html#sec_Meta">Application Versus Meta Instructions</a>) (which should not fault) and is not modifying, reordering, or removing application instructions, these details can be ignored. In that case the client's basic block and trace callbacks should return <a class="el" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a7d25c4546544d1a8c0b77c69230772eb">DR_EMIT_DEFAULT</a> in addition to being deterministic and idempotent (i.e., DynamoRIO should be able to repeatedly call the callback and receive back the same resulting instruction list, with no net state changes to the client).</p>
<p>If a client is performing modifications, then in order for DynamoRIO to properly translate a code cache address the client must use <a class="el" href="dr__ir__instr_8h.html#af1beda2d570ba04d74ca9cbd7c31bb1d">instr_set_translation()</a> (chainable via <a class="el" href="dr__ir__macros_8h.html#ad21fbdff8a5631b3e31b8221180a2a9c">INSTR_XL8()</a>) in the basic block and trace creation callbacks to set the corresponding application address for each added meta instruction that can fault, each modified instruction, and each added application instruction. The translation value is the application address that should be presented to the application as the faulting address, or the application address that should be restarted after a suspend. Currently the translation address must be within the existing range of source addresses for the basic block or trace.</p>
<p>There are two methods for using the translated addresses:</p>
<ol type="1">
<li>Return <a class="el" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a80b741b6a35dc7424940a873bfee2ced">DR_EMIT_STORE_TRANSLATIONS</a> from the basic block creation callback. DR will then store the translation addresses and use the stored information on a fault. The basic block callback for <code>tag</code> will not be called with <code>translating</code> set to true. Note that unless <a class="el" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a80b741b6a35dc7424940a873bfee2ced">DR_EMIT_STORE_TRANSLATIONS</a> is also returned for <code>for_trace</code> calls (or <a class="el" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a80b741b6a35dc7424940a873bfee2ced">DR_EMIT_STORE_TRANSLATIONS</a> is returned in the trace callback), each constituent block comprising the trace will need to be re-created with both <code>for_trace</code> and <code>translating</code> set to true. Storing translations uses additional memory that can be significant: up to 20% in some cases, as it prevents DR from using its simple data structures and forces it to fall back to its complex, corner-case design. This is why DR does not store all translations by default.</li>
<li>Return <a class="el" href="dr__events_8h.html#a689518ac5d1ad136b13e03012702b209a7d25c4546544d1a8c0b77c69230772eb">DR_EMIT_DEFAULT</a> from the basic block or trace creation callback. DynamoRIO will then call the callback again during fault translation with <code>translating</code> set to true. All modifications to the instruction list that were performed on the creation callback must be repeated on the translating callback. This option is only posible when basic block modifications are deterministic and idempotent, but it saves memory. Naturally, global state changes triggered by block creation should be wrapped in checks for <code>translating</code> being false. Even in this case, <a class="el" href="dr__ir__instr_8h.html#af1beda2d570ba04d74ca9cbd7c31bb1d">instr_set_translation()</a> should be called for appropriate instructions even when <code>translating</code> is false, as DynamoRIO may decide to store the translations at creation time for reasons of its own.</li>
</ol>
<p>Furthermore, if the client's modifications change any part of the machine state besides the program counter, the client should use <a class="el" href="dr__events_8h.html#ae7a179ac7a2d01157e1ab2852f50c902">dr_register_restore_state_event()</a> or <a class="el" href="dr__events_8h.html#a000e59a3f500a2d4a1d0123ce6032f77">dr_register_restore_state_ex_event()</a> (see <a class="el" href="API_BT.html#sec_events_translation">State Restoration</a>) to restore the registers to their original application values.</p>
<p>For meta instructions that do not reference application memory (i.e., they should not fault), leave the translation field as NULL. A NULL value instructs DynamoRIO to use the subsequent application instruction's translation as the application address, and to fail when translating the full state. Since the full state will only be needed when relocating a thread (as stated, there will not be a fault here), failure indicates that this is not a valid relocation point, and DynamoRIO's thread synchronization scheme will use another spot. If the translation field is set to a non-NULL value, the client should be willing to also restore the rest of the machine state at that point (restore spilled registers, etc.) via <a class="el" href="dr__events_8h.html#ae7a179ac7a2d01157e1ab2852f50c902">dr_register_restore_state_event()</a> or <a class="el" href="dr__events_8h.html#a000e59a3f500a2d4a1d0123ce6032f77">dr_register_restore_state_ex_event()</a>. This is necessary for meta instructions that reference application memory or that may deliberately fault when accessing client memory. DynamoRIO takes care of such potentially-faulting instructions added by its own API routines (<a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a> arguments that reference application data, <a class="el" href="dr__ir__utils_8h.html#a919e2106df67eaaa5bc6c49d736543b5">dr_insert_mbr_instrumentation()</a>'s read of application indirect branch data, etc.)</p>
<p>Here is an example of using the INSTR_XL8 macro to set the translation field for a meta instruction:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define PREM instrlist_meta_preinsert</span></div>
<div class="line"><span class="preprocessor"></span></div>
<div class="line">app_pc xl8 = <a class="code" href="dr__ir__instr_8h.html#a57dbc129ab88dfdcf49f1105eba394a7">instr_get_app_pc</a>(inst);</div>
<div class="line">PREM(bb, inst, <a class="code" href="dr__ir__macros_8h.html#ad21fbdff8a5631b3e31b8221180a2a9c">INSTR_XL8</a>(<a class="code" href="dr__ir__macros_8h.html#a9d0f07bc39f6e37f5f4a9836f342e077">INSTR_CREATE_mov_st</a>(drcontext, dst, src), xl8));</div>
</div><!-- fragment --> 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_pcache"></a>
Persisting Code</h1>
<p>Decoding, instrumenting, and emitting code into the code cache takes time. Short-running applications, or applications that execute large amounts of code with little code re-use, can incur noticeable overhead when run under DynamoRIO. One solution is to write the code cache to a file for fast re-use on subsequent runs by simply loading the file. DynamoRIO provides support for tools to persist their instrumented code.</p>
<p>First, the <a class="el" href="using.html#op_persist">-persist</a> runtime option, and optionally <code>-persist_dir</code>, must be set in order for any caches to be persisted. Only basic block persistence is supported: no traces. In the presence of a client, basic blocks by default are not persisted. Only if the return value of the basic block event callback includes the DR_EMIT_PERSISTABLE flag is a block eligible for persistence. Even then, there are further constraints on persistence, as only simple blocks are persistable.</p>
<p>Persisted caches end in the extension <code></code>.dpc, for DynamoRIO Persisted Cache, and are stored in the directory specified by the <code>-persist_dir</code> runtime option, or the log directory if unspecified, inside a per-user subdirectory.</p>
<p>A client may need to store data in the persisted file in order to determine whether it is re-usable when loaded again, or to provide generated code or other auxiliary data or code that the persisted code requires. A set of events are provided for this purpose. These events allow a client to store three types of data in a persisted file, beyond instrumented code inside each basic block: read-only data, executed code (outside of basic blocks), and writable data. The types of data are separated because the file is laid out in different protection zones. Read-only data can be added using <a class="el" href="dr__events_8h.html#a816faa7f555a3b53c4c8a79e3ce9f299">dr_register_persist_ro()</a>, executable code using <a class="el" href="dr__events_8h.html#a85e4007d8a1b7bba06809d97573fd84a">dr_register_persist_rx()</a>, and writable data using <a class="el" href="dr__events_8h.html#a47da83a410ee40275f92cb68de55d4aa">dr_register_persist_rw()</a>. Additionally, the basic blocks to be persisted can be patched using <a class="el" href="dr__events_8h.html#a30d782573b0448ce83fe6509e322629b">dr_register_persist_patch()</a>.</p>
<p>Whenever code is about to be persisted, DynamoRIO will call all of the registered events for that module. A user data parameter can be used to share information across the event callbacks.</p>
<p>Clients are cautioned to ensure their instrumentation is either position-independent or properly patched to operate correctly when the client library base or the persisted code addresses change. For example, if inserted instrumentation includes calls or jumps into the client library, these can be persisted unchanged if the client also stores its base address in the read-only section and in the resurrection callback checks it against its current base address. On a mismatch, the persisted file must be rejected. A more sophisticated approach requires indirection, position independence in the code, or patching.</p>
<p>DynamoRIO itself ensures that a persisted file is only re-used if its application module has not changed, if the set of clients in use is identical to those present on creation of the file, and that the TLS offset is identical. The application module check currently includes the base address on Windows, which precludes re-using persisted files for libraries loaded at different addresses via ASLR. (In the future we plan to provide application relocation support, but it is not there today.). The client check is based on the absolute paths. If a client needs to validate based on its runtime options, or do a version check based on its own changing instrumentation, it must do that on its own in the event callbacks. The TLS check ensures that TLS scratch slots are identical. DynamoRIO also ensures that any runtime options that affect persistent code (such as whether traces are enabled) are identical.</p>
 
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
 <h1><a class="anchor" id="sec_startstop"></a>
Running a Subset of an Application</h1>
<p>An alternative to running an entire application under DynamoRIO control is to use the Application Interface to specify a portion of the application to run. This interface consists of the following routines:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__app_8h.html#abcdedd068a4d264401c31767355ec218">dr_app_setup</a>()</div>
<div class="line"><a class="code" href="dr__app_8h.html#afb7b7aed03dd6f0ed8d48b8a8796e55e">dr_app_start</a>()</div>
<div class="line"><a class="code" href="dr__app_8h.html#afd509bb9ea5d1947228de48dda256e8f">dr_app_stop</a>()</div>
<div class="line"><a class="code" href="dr__app_8h.html#a216ee7d3e25b4c31edf5a9b2ba93d533">dr_app_cleanup</a>()</div>
<div class="line"><a class="code" href="dr__app_8h.html#a43dead944cb3c75de2537404b568f8ec">dr_app_take_over</a>()</div>
</div><!-- fragment --><p>When building an executable that uses DynamoRIO's Application Interface, follow the steps for <a class="el" href="using.html#sec_build">Building a Client</a> to include the header files and link with the DynamoRIO library, but omit the linker flags requesting no standard libraries or startup files. DynamoRIO's CMake support does this automatically, as the linker flags for shared libraries are separate from those for executables. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
